<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Lower-level Primitives
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot111.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot104.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot113.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc243">17.8</A>&nbsp;&nbsp;Lower-level Primitives</H2><UL>
<LI><A HREF="umsroot112.html#toc133">Suspensions and Suspension Lists</A>
<LI><A HREF="umsroot112.html#toc134">Creating Suspended Goals</A>
<LI><A HREF="umsroot112.html#toc135">Operations on Suspensions</A>
<LI><A HREF="umsroot112.html#toc136">Examining the Resolvent</A>
<LI><A HREF="umsroot112.html#toc137">Attaching Suspensions to Variables</A>
<LI><A HREF="umsroot112.html#toc138">User-defined Suspension Lists</A>
<LI><A HREF="umsroot112.html#toc139">Attaching Suspensions to Global Triggers</A>
<LI><A HREF="umsroot112.html#toc140">Scheduling Suspensions for Waking</A>
</UL>


Suspended goals are actually represented by a special
opaque data type, called <B>suspension</B>, which can be explicitly
manipulated under program control using the primitives defined in
this section.
Although usually a suspended goal waits for some waking condition
in order to be reactivated, the primitives for suspension handling
do not enforce this. To provide maximum flexibility of use,
the functionalities of suspending and waking/scheduling are
separated from the trigger mechanisms that cause the waking. <BR>
<BR>
<A NAME="@default988"></A><BR>
<BR>
<A NAME="toc133"></A>
<H3 CLASS="subsection"><A NAME="htoc244">17.8.1</A>&nbsp;&nbsp;Suspensions and Suspension Lists</H3>
A suspension represents a goal that is part of the resolvent.
Apart from the goal structure proper, it holds information that
is used for controlling its execution.
The components of a suspension are:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>The goal structure</B><DD CLASS="dd-description">
 A term representing the goal itself, eg. <EM>X &gt;Y</EM>.
<DT CLASS="dt-description"><B>The goal module</B><DD CLASS="dd-description">
 The module from which the goal was called.
<DT CLASS="dt-description"><B>The goal priority</B><DD CLASS="dd-description">
 The priority with which the goal will be scheduled when
 it becomes woken.
<DT CLASS="dt-description"><B>The state</B><DD CLASS="dd-description">
 This indicates the current position of the suspension within
 the resolvent. It is either suspended (sleeping), scheduled
	or executed (dead).
<DT CLASS="dt-description"><B>Additional data</B><DD CLASS="dd-description">
	E.g. debugging information.
</DL>
Suspensions which should be woken by the same event are grouped
together in a <I>suspension list</I>.
<A NAME="@default989"></A>
Suspension lists are either stored in an attribute of
an attributed variable or attached to a symbolic trigger.<BR>
<BR>
<A NAME="toc134"></A>
<H3 CLASS="subsection"><A NAME="htoc245">17.8.2</A>&nbsp;&nbsp;Creating Suspended Goals</H3>
<A NAME="@default990"></A>
The most basic primitive to create a suspension is
<A HREF="../bips/kernel/suspensions/make_suspension-3.html"><B>make_suspension(Goal, Priority, Susp [, Module])</B></A><A NAME="@default991"></A>
where <B>Goal</B> is the goal structure,
<B>Priority</B> is a small integer denoting the priority with which
the goal should be woken and <B>Susp</B> is the resulting suspension.<BR>
<BR>
Note that usually
<A HREF="../bips/kernel/suspensions/make_suspension-3.html"><B>make_suspension/3,4</B></A><A NAME="@default992"></A>
is not used directly, but implicitly via
<A HREF="../bips/kernel/suspensions/suspend-3.html"><B>suspend/3,4</B></A><A NAME="@default993"></A> 
(described in section <A HREF="umsroot110.html#suspend3">17.6</A>) which in addition attaches the suspension to a
trigger condition.<BR>
<BR>
A suspension which has not yet been scheduled
for execution and executed, is called <EM>sleeping</EM>,
<A NAME="@default994"></A>
a suspension which has already been executed is called
<EM>executed</EM> or <EM>dead</EM> (since it disappears from the resolvent,
but see section <A HREF="umsroot113.html#secdemon">17.9</A> for an exception).
<A NAME="@default995"></A>
A newly created suspension is always sleeping, however
note that due to backtracking, an executed suspension
can become sleeping again.
<A NAME="@default996"></A>
Sometimes we use the term <EM>waking</EM>, which is less precise and
denotes the process of both scheduling and eventual execution.<BR>
<BR>
By default, suspensions are printed as follows (the variants with invocation
numbers are used when the debugger is active):
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=center NOWRAP>'SUSP-_78-susp'		</TD>
<TD ALIGN=left NOWRAP>	sleeping suspension with id _78</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>'SUSP-_78-sched'	</TD>
<TD ALIGN=left NOWRAP>	scheduled suspension with id _78</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>'SUSP-_78-dead'		</TD>
<TD ALIGN=left NOWRAP>	dead suspension with id _78</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>'SUSP-123-susp'		</TD>
<TD ALIGN=left NOWRAP>	sleeping suspension with invocation number 123</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>'SUSP-123-sched'	</TD>
<TD ALIGN=left NOWRAP>	scheduled suspension with invocation number 123</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>'SUSP-123-dead'		</TD>
<TD ALIGN=left NOWRAP>	dead suspension with id invocation number 123</TD>
</TR></TABLE>
</DIV>
It is possible to change the way suspensions are printed by defining a 
<A HREF="../bips/kernel/syntax/portray-3.html"><B>portray/3</B></A><A NAME="@default997"></A>
transformation for the term type <TT>goal</TT>.<BR>
<BR>
<A NAME="toc135"></A>
<H3 CLASS="subsection"><A NAME="htoc246">17.8.3</A>&nbsp;&nbsp;Operations on Suspensions</H3>
The following summarises the predicates that can be used to create, test,
decompose and destroy suspensions.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/kernel/suspensions/make_suspension-3.html"><B>make_suspension(Goal, Priority, Susp)</B></A><A NAME="@default998"></A><DD CLASS="dd-description">
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/make_suspension-4.html"><B>make_suspension(Goal, Priority, Susp, Module)</B></A><A NAME="@default999"></A><DD CLASS="dd-description">
Create a suspension <B>Susp</B> with a given priority from a given goal.
The goal will subsequently show up as a <I>delayed goal</I>.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/typetest/is_suspension-1.html"><B>is_suspension(Susp)</B></A><A NAME="@default1000"></A><DD CLASS="dd-description">
Succeeds if <B>Susp</B> is a sleeping or scheduled suspension,
fails if it is not a suspension or a suspension that has been already executed.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/typetest/type_of-2.html"><B>type_of(S, goal)</B></A><A NAME="@default1001"></A><DD CLASS="dd-description">
Succeeds if <B>S</B> is a suspension, no matter if it is
sleeping, scheduled or executed.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/get_suspension_data-3.html"><B>get_suspension_data(Susp, Name, Value)</B></A><A NAME="@default1002"></A><DD CLASS="dd-description">
Extract any of the information contained in the suspension:
<B>Name</B> can be one of
<CODE>goal</CODE>, <CODE>module</CODE>, <CODE>priority</CODE>, <CODE>state</CODE> or <CODE>invoc</CODE> (debugger invocation number).<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/set_suspension_data-3.html"><B>set_suspension_data(Susp, Name, Value)</B></A><A NAME="@default1003"></A><DD CLASS="dd-description">
The <CODE>priority</CODE> and <CODE>invoc</CODE> (debugger invocation number) fields
of a suspension can be changed using this primitive.
If the priority of a sleeping suspension is changed,
this will only have an effect at the time the suspension gets
scheduled. If the suspension is already scheduled, changing
priority has no effect, except for future schedulings of demons
(see&nbsp;<A HREF="umsroot113.html#secdemon">17.9</A>).<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/kill_suspension-1.html"><B>kill_suspension(Susp)</B></A><A NAME="@default1004"></A><DD CLASS="dd-description">
Convert the suspension <B>Susp</B> into an <I>executed</I>
one, ie. remove the suspended goal from the resolvent.
This predicate is meta-logical as its use may
change the semantics of the program.
</DL>
<A NAME="toc136"></A>
<H3 CLASS="subsection"><A NAME="htoc247">17.8.4</A>&nbsp;&nbsp;Examining the Resolvent</H3>
The system keeps track of all created suspensions and it
uses this data e.g. in the built-in predicates
<A HREF="../bips/kernel/suspensions/delayed_goals-1.html"><B>delayed_goals/1</B></A><A NAME="@default1005"></A>,
<A HREF="../bips/kernel/suspensions/suspensions-1.html"><B>suspensions/1</B></A><A NAME="@default1006"></A>,
<A HREF="../bips/kernel/suspensions/current_suspension-1.html"><B>current_suspension/1</B></A><A NAME="@default1007"></A>,
<A HREF="../bips/kernel/suspensions/subcall-2.html"><B>subcall/2</B></A><A NAME="@default1008"></A>
<A NAME="@default1009"></A>
and to detect floundering of the query given to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> top-level loop.<BR>
<BR>
<A NAME="toc137"></A>
<H3 CLASS="subsection"><A NAME="htoc248">17.8.5</A>&nbsp;&nbsp;Attaching Suspensions to Variables</H3>

Suspensions are attached to variables by means of the attribute mechanism.
<A NAME="@default1010"></A>
For this purpose, a variable attribute needs to have one or more slots
reserved for <B>suspension lists</B>.
<A NAME="@default1011"></A>
Suspensions can then be inserted into one or several of those lists using
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/kernel/suspensions/insert_suspension-3.html"><B>insert_suspension(Vars, Susp, Index)</B></A><A NAME="@default1012"></A><DD CLASS="dd-description">
Insert the suspension <B>Susp</B> into the <B>Index</B>'th
suspension list of all attributed variables occurring in <B>Vars</B>.
The current module specifies which of the attributes will be taken.<BR>
<BR>
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/insert_suspension-4.html"><B>insert_suspension(Vars, Susp, Index, Module)</B></A><A NAME="@default1013"></A><DD CLASS="dd-description">
Similar to <A HREF="../bips/kernel/suspensions/insert_suspension-3.html"><B>insert_suspension/3</B></A><A NAME="@default1014"></A>,
but it inserts the suspension into the attribute specified by <B>Module</B>.
</DL>
For instance,
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
insert_suspension(Vars, Susp, inst of suspend, suspend)
</PRE></BLOCKQUOTE>
inserts the suspension into the <B>inst</B>list of the (system-predefined) <B>suspend</B>
attribute of all variables that occur in <B>Vars</B>, and
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
insert_suspension(Vars, Susp, max of fd, fd)
</PRE></BLOCKQUOTE>
would insert the suspension into the <B>max</B> list of the finite-domain
attribute of all variables in <B>Vars</B>.<BR>
<BR>
Note that both predicates
find all attributed variables which occur in the general term <B>Vars</B> and for each of them,
locate the attribute which corresponds to the current module or the
<B>Module</B> argument respectively.
This attribute must be a structure, otherwise an error
is raised, which means that the attribute has to be initialised
before calling
<A HREF="../bips/kernel/suspensions/insert_suspension-4.html"><B>insert_suspension/4,3</B></A><A NAME="@default1015"></A>.
Finally, the <B>Index</B>'th argument of the attribute
is interpreted as a suspension list and the suspension
<B>Susp</B> is inserted at the beginning of this list.
A more user-friendly interface to access suspension lists is
provided by the
<A HREF="../bips/kernel/suspensions/suspend-3.html"><B>suspend/3</B></A><A NAME="@default1016"></A>
predicate.<BR>
<BR>
<A NAME="toc138"></A>
<H3 CLASS="subsection"><A NAME="htoc249">17.8.6</A>&nbsp;&nbsp;User-defined Suspension Lists</H3>
Many important attributes and suspension lists are either provided by
the suspend-attribute or by libraries like the interval solver library lib(ic).
For those suspension lists, initialisation and waking is taken care of
by the library code.<BR>
<BR>
For the implementation of user-defined suspension lists,
the following low-level primitives are provided:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A HREF="../bips/kernel/suspensions/init_suspension_list-2.html"><B>init_suspension_list(+Position, +Attribute)</B></A><A NAME="@default1017"></A><DD CLASS="dd-description">
 Initialises argument Position of Attribute to an empty suspension list.
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/merge_suspension_lists-4.html"><B>merge_suspension_lists(+Pos1, +Attr1, +Pos2, +Attr2)</B></A><A NAME="@default1018"></A><DD CLASS="dd-description">
 Destructively appends the first suspension list (argument Pos1 of Attr1) to
 the end of the second (argument Pos2 of Attr2).
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/enter_suspension_list-3.html"><B>enter_suspension_list(+Pos, +Attr, +Susp)</B></A><A NAME="@default1019"></A><DD CLASS="dd-description">
 Adds the suspension Susp to the suspension list in the
 argument position Pos of Attr. The suspension list can be pre-existing,
 or the argument could be uninstantiated, in which case a new suspension
 list will be created.
<DT CLASS="dt-description"><A HREF="../bips/kernel/suspensions/schedule_suspensions-2.html"><B>schedule_suspensions(+Position, +Attribute)</B></A><A NAME="@default1020"></A><DD CLASS="dd-description">
 Takes the suspension list on argument position <B>Position</B> within
 <B>Attribute</B>, and schedule them for execution. 
 As a side effect, the suspension list within <B>Attribute</B> is updated,
 ie. suspensions which are no longer useful are removed destructively.
 See section <A HREF="#secwaking">17.8.8</A> for more details on waking.
</DL>
<A NAME="toc139"></A>
<H3 CLASS="subsection"><A NAME="htoc250">17.8.7</A>&nbsp;&nbsp;Attaching Suspensions to Global Triggers</H3>
<A NAME="@default1021"></A>
<A NAME="@default1022"></A>
A single suspension or a list of suspensions can be attached to a
symbolic trigger by using
<A HREF="../bips/kernel/suspensions/attach_suspensions-2.html"><B>attach_suspensions(+Trigger, +Susps)</B></A><A NAME="@default1023"></A>.
A symbolic trigger can have an arbitrary name (an atom).
<BR>
<BR>
<A NAME="toc140"></A>
<H3 CLASS="subsection"><A NAME="htoc251">17.8.8</A>&nbsp;&nbsp;Scheduling Suspensions for Waking</H3>
<A NAME="secwaking"></A><A NAME="@default1024"></A>Suspended goals are woken by submitting at least one of the suspension lists
in which they occur to the waking scheduler.
The waking scheduler which maintains a global priority queue inserts
them into this queue according to their priority (see figure <A HREF="umsroot106.html#figresolv">17.1</A>).
A suspension list can be passed to the scheduler by either of the predicates
<A HREF="../bips/kernel/suspensions/schedule_suspensions-1.html"><B>schedule_suspensions/1</B></A><A NAME="@default1025"></A>
(for triggers)
or
<A HREF="../bips/kernel/suspensions/schedule_suspensions-2.html"><B>schedule_suspensions/2</B></A><A NAME="@default1026"></A>
(for uder-defined suspension lists).
A suspension which has been scheduled in this way and awaits
its execution is called a <I>scheduled suspension</I>.<BR>
<BR>
Note, however, that scheduling a suspension by means of
<A HREF="../bips/kernel/suspensions/schedule_suspensions-1.html"><B>schedule_suspensions/1</B></A><A NAME="@default1027"></A>
or
<A HREF="../bips/kernel/suspensions/schedule_suspensions-2.html"><B>schedule_suspensions/2</B></A><A NAME="@default1028"></A>
alone does not implicitly start the waking scheduler.
Instead, execution continues normally with the next goal in sequence after
schedule_suspensions/1,2.
The scheduler must be explicitly invoked by calling 
<A HREF="../bips/kernel/suspensions/wake-0.html"><B>wake/0</B></A><A NAME="@default1029"></A>.
Only then does it start to execute the woken suspensions.<BR>
<BR>
The reason for having <A HREF="../bips/kernel/suspensions/wake-0.html"><B>wake/0</B></A><A NAME="@default1030"></A>
is to be able to schedule several suspension lists before the
priority-driven execution begins<SUP><A NAME="text30" HREF="umsroot104.html#note30">5</A></SUP>.<BR>
<BR>
<A NAME="@default1031"></A><BR>
<BR>
<HR>
<A HREF="umsroot111.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot104.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot113.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
